Add new linting rule and fix documentation being broken

Author: leeyi45

.github/workflows/pull-request.yml

@@ -39,6 +39,12 @@ jobs:
         id: info
         uses: ./.github/actions/src/info
 
+      - name: Echo Information about docserver
+        run: echo ${{ steps.info.outputs.docserver }}
+
+      - name: Echo Information about devserver
+        run: echo ${{ steps.info.outputs.devserver }}
+
     outputs:
       bundles: ${{ steps.info.outputs.bundles }}
       libs: ${{ steps.info.outputs.libs }}
@@ -221,7 +227,7 @@ jobs:
     needs:
       - libraries
       - find-packages
-    if: ${{ needs.find-packages.outputs.docserver.changes == 'true' }}
+    if: ${{ needs.find-packages.outputs.docserver.changes }}
 
     steps:
       - name: Check out source code
@@ -255,3 +261,12 @@ jobs:
 
       - name: Lint Everything
         run: yarn lint:all
+
+      - name: Build Manifest
+        run: yarn buildtools manifest
+
+      - name: Upload Manifest
+        uses: actions/upload-artifact@v4
+        with:
+          name: manifest
+          path: ./build/modules.json

.vscode/settings.json

@@ -18,10 +18,11 @@
     }
   ],
   "eslint.validate": [
+    "github-actions-workflow",
     "javascript",
     "javascriptreact",
     "json",
-    "mdx",
+    "markdown",
     "typescript",
     "typescriptreact",
     "yml",

docs/src/lib/dev/curve.md

@@ -1,5 +1,5 @@
 ---
-title: curve
+title: Curve Bundle
 ---
 
 # Introduction

docs/src/lib/dev/devdocs.data.ts

@@ -6,12 +6,23 @@ import { createContentLoader } from 'vitepress';
 
 const files = await fs.readdir(import.meta.dirname, { withFileTypes: true });
 
+// Any markdown files within the lib/dev directory will be considered
+// except for the index.md file
 const filesToInclude = files.filter(each => {
   if (!each.isFile()) return false;
   if (pathlib.extname(each.name) !== '.md') return false;
   return each.name !== 'index.md';
 }).map(each => {
+  // Paths are resolved relative to the src directory
   return pathlib.join('/lib/dev', each.name);
 });
 
-export default createContentLoader(filesToInclude);
+export default createContentLoader(filesToInclude, {
+  transform(data) {
+    // Append the base path
+    data.forEach(each => {
+      each.url = `/devdocs${each.url}`;
+    });
+    return data;
+  }
+});

docs/src/lib/dev/game.md

@@ -1,5 +1,5 @@
 ---
-title: game
+title: Game Bundle
 ---
 
 # Introduction

docs/src/lib/index.md

@@ -1,7 +1,7 @@
-## Modules Developer Documentation
+# Modules Developer Documentation
 If you're developing for a specific module, its developer documentation can be found under [this](./dev/) section.
 
-## Common Modules Libraries
+# Common Libraries
 
 - [Lint Plugin](./lintplugin/)
 - [Modules Lib](./modules-lib/)

docs/src/lib/lintplugin/2-rules.md

@@ -51,6 +51,138 @@ import path from 'pathlib'
 // both import statements will be validated!
 ```
 
+## `no-barrel-imports`
+Enforces that imports from a certain source uses individual imports intead of the main barrel import.
+
+This rule was primarily motivated by packages like `lodash` and `@mui`, which re-export all their functionalities
+through the main export, but also make each function available in a separate package:
+```ts
+// Imports from the root package
+import _ from 'lodash'
+_.memoize(func)
+
+import { memoize } from 'lodash'
+memoize(func)
+// vs importing from a "sub-package"
+import memoize 'lodash/memoize'
+memoize(func)
+```
+
+The reason for these "per method imports" is to help bundlers more effectively tree-shake and thus more effectively reduce final bundle size.
+
+> [!INFO] Why not directly use "per method packages"?
+> In theory, `lodash` provides its sub-packages as actual packages you can install separately without having to install the entire `lodash` bundle.
+> However, the `lodash` [documentation](https://lodash.com/per-method-packages) recommends against this practice for reasons mentioned there.
+
+The exception to this is Typescript "type-only" imports, since those automatically get removed from the output source code:
+```ts
+// Are perfectly ok
+import type _ from 'lodash'
+import type { memoize } from 'lodash'
+```
+
+### Fixes
+The rule replaces the original import with different import statements from each of the subpackages:
+```ts
+import { memoize } from 'lodash'
+// gets autofixed to
+import memoize from 'lodash/memoize'
+```
+
+If you aliased the import, the appropriate alias name will be used:
+```ts
+import { memoize as func } from 'lodash'
+// gets autofixed to
+import func from 'lodash/memoize'
+```
+
+Multiple imports from the root package get transformed like this:
+```ts
+import { memoize as func, cloneDeep } from 'lodash'
+// gets autofixed to
+import func from 'lodash/memoize'
+import cloneDeep from 'lodash/cloneDeep'
+import cloneDeep from 'lodash/cloneDeep'
+```
+
+Type-only imports, when mixed with default imports, also get autofixed:
+```ts
+import { type memoize as func, cloneDeep } from 'lodash'
+// gets autofixed to
+import type func from 'lodash/memoize'
+import cloneDeep from 'lodash/cloneDeep'
+```
+
+> [!WARNING]
+> This only tells the rule what import sources to check for. It doesn't perform any kind of verification that the sub-package export paths
+> are actually available. For example, the rule will not actually verify that `lodash/memoize` is a valid import path and that it does have a default export
+
+### Options
+The rule should be configured with an array of package names to check:
+```ts
+rules: {
+  '@sourceacademy/no-barrel-imports': ['error', ['lodash']]
+}
+```
+
+
+### ✅ Examples of **correct** code for this rule:
+
+```ts
+// with @sourceacademy/no-barrel-imports: ['error', ['lodash']]
+
+// Lone default or namespace imports are ok
+import _ from 'lodash'
+import * as _ from 'lodash'
+
+// Type-only imports are okay
+import type _ from 'lodash';
+import type { memoize } from 'lodash';
+```
+
+### ❌ Examples of **incorrect** code for this rule:
+```ts
+// with @sourceacademy/no-barrel-imports: ['error', ['lodash']]
+
+// Regular Import
+import { memoize } from 'lodash'
+
+// Default import mixed with type imports
+import _, { type memoize } from 'lodash';
+```
+
+## `region-comment`
+This rule enforces that each `// #region` comment is named and paired with a corresponding `// #endregion` comment.
+
+### ✅ Examples of **correct** code for this rule:
+```ts
+// #region Region1
+export function foo() {}
+// #endregion Region1
+```
+
+Regions can overlap:
+```ts
+// #region Region1
+// #region Region2
+export function foo() {}
+// #endregion Region2
+// #endregion Region1
+```
+
+### ❌ Examples of **incorrect** code for this rule:
+
+```ts
+// Missing name for region
+// #region
+export function foo() {}
+// #endregion
+
+// Missing #region tag
+export function bar() {}
+// #endregion 1
+```
+
 ## `tab-type`
 
 Enforces that tabs have a default export using the `defineTab` helper.
@@ -108,34 +240,3 @@ export default tabHelper({
 });
 ```
 
-## `region-comment`
-This rule enforces that each `// #region` comment is named and paired with a corresponding `// #endregion` comment.
-
-### ✅ Examples of **correct** code for this rule:
-```ts
-// #region Region1
-export function foo() {}
-// #endregion Region1
-```
-
-Regions can overlap:
-```ts
-// #region Region1
-// #region Region2
-export function foo() {}
-// #endregion Region2
-// #endregion Region1
-```
-
-### ❌ Examples of **incorrect** code for this rule:
-
-```ts
-// Missing name for region
-// #region
-export function foo() {}
-// #endregion
-
-// Missing #region tag
-export function bar() {}
-// #endregion 1
-```

docs/src/lib/lintplugin/3-config.md

@@ -1,5 +1,5 @@
 ---
-title: Configurations
+title: Config Reference
 ---
 <script setup>
   import { data } from './configs.data.ts';

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

@@ -56,10 +56,6 @@ documentation in those pages or create rewrites so that users are automatically
 
 Instead, the links in the sidebar link to the page (if it is a markdown file), or to a child within the folder that has the same name as that folder.
 
-The specific configuration for this behaviour can be found in the Vitepress config file, and the documentation for those options can be found on the Vitepress website:
-
-<<< ../../../.vitepress/config.ts {65-75 ts:line-numbers}
-
 ## Documentation for `modules-lib`
 The documentation for `@sourceacademy/modules-lib` is automatically generated by Typedoc. The configuration options for this generation are found in that folder. The documentation for `@sourceacademy/modules-lib` should be built before this server is built.
 

eslint.config.js

@@ -160,6 +160,7 @@ export default tseslint.config(
       'no-empty': ['error', { allowEmptyCatch: true }],
 
       '@sourceacademy/default-import-name': ['warn', { path: 'pathlib' }],
+      '@sourceacademy/no-barrel-imports': ['error', ['lodash']],
       '@sourceacademy/region-comment': 'error',
 
       '@stylistic/brace-style': ['warn', '1tbs', { allowSingleLine: true }],