Core/cli fix

.github/workflows/check-repo.yml

@@ -21,4 +21,6 @@ jobs:
       - name: Unit Tests
         run: npm test
       - name: Lint
-        run: npm run lint
+        run: |
+          npm run lint
+          npm run pretty

README.md

@@ -84,6 +84,12 @@ SfeirThemeInitializer.init(formation);
 
 Enjoy!
 
+# CLI
+
+This repo also ships a CLI to check and scaffold your training: it validates slides, labs and assets against the theme's conventions.
+
+See the [CLI documentation](./cli/README.md) for installation, commands and configuration.
+
 # RevealJS
 
 This theme use target for [RevealJS](https://revealjs.com/#/) so all you can do with RevealJS is available with theme.

cli/README.md

@@ -1,6 +1,198 @@
 # CLI
 
-## Check
+The Sfeir School Theme CLI will provide you better Sfeir School Theme experience:
+
+- Check classes and markdown syntax;
+- Images check;
+- Slide declaration check;
+- Labs declaration check;
+- Ensure some convention;
+
+The ultimate goals of the CLI are:
+
+- Avoid a lot a friction when build training with the Sfeir School Theme;
+- Ensure the training stay cleaned up (no old image, no unused markdown files, etc.);
+- Ensure a minimal coherence between training, so when you go on another training you will not be lost;
+
+## Installation
+
+Add to the `docs/package.json`:
+
+```JSON
+{
+    ...
+    "scripts": {
+        ...
+        "test": "sfeir-school-theme check --rootDir=..",
+        ...
+    }
+    ...
+}
+```
+
+Add the pipeline `.github/workflows/check-repo.yml`:
+
+```Yaml
+name: CI/CD
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  check-repo:
+    timeout-minutes: 60
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: ./docs
+    permissions: write-all
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20.9
+      - name: Install dependencies
+        run: npm ci
+      - name: Unit Tests
+        run: npm test
+
+```
+
+Init the configuration file (on the training root directory):
+
+```Bash
+npx sfeir-school-theme init-config
+
+# From other directory:
+npx sfeir-school-theme init-config --rootDir=path/to/training/root/directory
+```
+
+This command will create `.sfeir-theme-config.json` file.
+
+## Basic usage
+
+### Check the Training
+
+```Bash
+# In the training root directory:
+npx sfeir-school-theme check
+
+# From other directory:
+npx sfeir-school-theme check --rootDir=path/to/training/root/directory
+```
+
+If everything is good, you should see:
+
+```
+OK
+```
+
+If there is errors:
+
+```
+[CheckError] S_003 "00-school/00-TITLE.md" should be used
+
+You can call "sfeir-school-theme explain S_003" to have more details.
+```
+
+Every error will have a rule code `<ONE_LETTER>_<RULE_ID>` (in the above example: `S_003`).
+
+### Explain
+
+The CLI let you get the documentation directly:
+
+```Bash
+npx sfeir-school-theme explain S_003
+```
+
+### Get school info
+
+This command will give you the lab list
+
+```Bash
+npx sfeir-school-theme info
+
+# From other directory:
+npx sfeir-school-theme info --rootDir=path/to/training/root/directory
+```
+
+```
+# Labs
+
+ - 01-ouverture-de-l-usine(-solution)
+ - 02-preparer-la-pate(-solution)
+ - 03-preparer-les-pommes(-solution)
+ - 04-foncer-la-tarte(-solution)
+ - 05-cuire-la-tarte(-solution)
+ - 06-tests(-solution)
+ - 99-bonus-simple-mapping(-solution)
+ - 100-bonus-chevre-chaud(-solution)
+```
+
+### Get school theme version
+
+This command will give you the lab list
+
+```Bash
+npx sfeir-school-theme version
+```
+
+```
+Version: 4.0.0-rc-14
+```
+
+## Configuration files
+
+The `.sfeir-theme-config.json` file (created via `init-config`) lets you override the CLI's default behavior for your training. Every key is optional and has a sane default; each one only affects the specific rules listed below.
+
+### extraCssFiles: string[] (optional)
+
+Default: `[]`
+
+You can specify here training css files. If you defined new css classes, these classes will be considered for S_009.
+
+**Impacts:** `S_009` only.
+
+### stepCommandPrefix: string (optional)
+
+Default: `""`
+
+If you specify `stepCommandPrefix`, every command of the training will be excepted to start with this prefix.
+
+For example, if you defined `"stepCommandPrefix": "npm run "`, your lab slide should look like:
+
+```Markdown
+<!-- .slide: class="exercice" -->
+
+# Lab title
+
+## Lab
+
+...
+
+### npm run lab-name
+```
+
+**Impacts:** without it, `L_007` and the strict part of `S_005`/`S_011` are entirely skipped (no check runs at all). `L_001` still runs, but only does a loose substring match on the lab name without requiring the prefix — a false negative risk if the lab name happens to appear elsewhere in the slide.
+
+### ignoreStepsDirectories: string[] (optional)
+
+Default: `[]`
+
+You can specify here every directories which are not lab but need to be in the `steps` directory (node_modules, common modules, data, etc.)
+
+**Impacts:** every `L_00X` rule. A listed directory is excluded from the lab set entirely, so it is never expected to have a README, a solution, a workspace declaration, etc.
+
+### ignoreAssets: string[] (optional)
+
+Default: `[]`
+
+Every assets here will be ignored. So S_008 will not emit any warning or error.
+
+**Impacts:** `S_008` only.
+
+## Rules
 
 ### Global checks
 
@@ -38,6 +230,18 @@ The root directory should contains a minimal structure:
     ├── ...
 ```
 
+##### G_004 the `<root>/CONTRIBUTION-GUIDE.md` file should exists and contains required content
+
+To ensure every trainer to be able to work smoothly on any training, a file `<root>/CONTRIBUTION-GUIDE.md` should be present and contains required sections.
+
+The required sections are:
+
+- How to start the slides on local?
+- How to start a lab?
+- How to add a new lab?
+- What tasks to do before push a PR?
+- What are the specific rules of this training?
+
 ### Slides checks
 
 #### General slides checks
@@ -86,7 +290,7 @@ Every markdown files in the `<root>/docs/markdown` directory should be declared
 
 #### Lab slides specific checks
 
-##### S_004 every lab slide file contains the command to run the exercise
+##### S_005 every lab slide file contains the valid command to run the exercise
 
 Every labs should have the expected format:
 
@@ -115,9 +319,11 @@ Notes:
 
 The command should start with `stepCommandPrefix` specified in the `<root>/.sfeir-theme-config.json`. This command should also contains an existing lab command.
 
-##### S_005 every lab slide file contains the valid command to run the exercise
+##### S_011 every lab slide should refer an existing lab
 
-Every labs should have the expected format:
+Every lab referred in a lab slide should match an existing lab directory in the `<root>/steps` directory.
+
+Example of lab slide referencing `01-getting-started` lab
 
 ```Markdown
 <!-- .slide: class="exercice" -->
@@ -136,17 +342,37 @@ Every labs should have the expected format:
 
 - note for the students
 
-### command to run
-
-Notes:
-- eventual speaker notes
+### 01-getting-started
 ```
 
-The command should start with `stepCommandPrefix` specified in the `<root>/.sfeir-theme-config.json`. This command should also contains an existing lab command.
+And we expect the `01-getting-started` directory exist.
+
+```
+<root>
+...
+└── steps
+    ├── 01-getting-started
+    ├── ...
+```
 
 ##### S_006 every lab slide should have lab format
 
-Every labs should have the expected format:
+Every labs should have the expected format. You should have at least two things to be compliant:
+
+- `<!-- .slide: class="exercice" -->` at the beginning of the slide;
+- `## Lab` to have a "Lab" mention visible;
+
+Minimal example:
+
+```Markdown
+<!-- .slide: class="exercice" -->
+
+# Lab title
+
+## Lab
+```
+
+Full example:
 
 ```Markdown
 <!-- .slide: class="exercice" -->
@@ -183,6 +409,8 @@ Every images linked in a slide should exists in the assets directory `<root>/doc
 
 Every images in `<root>/docs/assets/images/` directory should be linked in a slide.
 
+Note: images referenced in `ignoreAssets` in the configuration file will be ignored.
+
 #### CSS classes
 
 ##### S_009 every classes used in slide files should be known
@@ -199,7 +427,28 @@ Every classes used in a slide file should exists:
 
 ##### L_001 every labs should be used in a slide
 
-Every lab should be referenced in the lab slide.
+Every lab should be referenced in the lab slide. Lab is considered referenced when the lab name is present in a lab slide.
+
+Example:
+
+If you have a lab named `01-getting-started`, you should have a lab slide like:
+
+```
+<!-- .slide: class="exercice" -->
+
+# Getting started
+
+## Lab
+
+<br>
+
+1. first thing to do
+2. second thing to do
+
+### 01-getting-started
+```
+
+Note: if you have configured a command prefix (check `stepCommandPrefix` option for more details), the last lab slide row should be `### <stepCommandPrefix><lab name>`. For example, with `stepCommandPrefix: "npm run "`, you should have `### npm run 01-getting-started`.
 
 #### Workspace / Scripts checks
 
@@ -270,37 +519,42 @@ npm run 01-getting-started
 
 ##### L_006 every lab `README.md` should have correct title
 
-Every lab directory in `<root>/steps/` should contain a `README.md` file with the lab title and the correct command.
+Every lab directory in `<root>/steps/` should contain a `README.md` file whose title matches the lab name.
 
 Example of minimal `README.md`:
 
 ```Markdown
-# 01-getting-started instructions
+# **01-getting-started** instructions
 
 npm run 01-getting-started
 ```
+
 ##### L_007 every lab `README.md` should contains the correct command to start the lab
 
-Every lab directory in `<root>/steps/` should contain a `README.md` file with the lab title and the correct command.
+Every lab directory in `<root>/steps/` should contain a `README.md` file with the correct command to start the lab.
 
 Example of minimal `README.md`:
 
 ```Markdown
 # 01-getting-started instructions
 
-npm run 01-getting-started
+**npm run 01-getting-started**
 ```
 
+Note: this rule is only applied if you have specified `stepCommandPrefix` specified in the `<root>/.sfeir-theme-config.json`.
+
 #### Solutions checks
 
 ##### L_008 every lab should have solution
 
 Every lab should have a equivalent solution's lab. For example, if you create a lab "01-getting-started", you should create an other lab "01-getting-started-solution".
 
+Note: if it does not make sense to have a solution to a specific lab, you can add a `.nosolution` file and omit the lab solution. If you add a `.nosolution`, you should not add a lab solution.
+
 ##### L_009 every solution directory should match a lab
 
 Every lab with `-solution` suffix should match a lab with the exact same name without the `-solution` suffix.
 
 ##### L_010 every solution `README.md` should be the same as the lab's one
 
-Both lab and solution's lab should have the same `README.md` file content.
+You can omit solution's lab `README.md`, but if you add one: both lab and solution's lab should have the same `README.md` file content.