docs: more explanation

joj3_config_generator/main.py

@@ -95,6 +95,12 @@ def convert(
     app.pretty_exceptions_enable = False
     logger.info(f"Converting files in {root.absolute()}")
     for repo_toml_path in root.glob("**/repo.toml"):
+        if not any(p != repo_toml_path for p in repo_toml_path.parent.glob("*.toml")):
+            fallback_toml_path = repo_toml_path.parent / "conf.toml"
+            if not fallback_toml_path.exists():
+                fallback_toml_path.write_text(
+                    'name = "invalid commit"\nmax-total-score = 0\n'
+                )
         for task_toml_path in repo_toml_path.parent.glob("**/*.toml"):
             if repo_toml_path == task_toml_path:
                 continue

tests/convert/empty/task.json

@@ -0,0 +1,182 @@
+{
+    "name": "invalid commit",
+    "logPath": "/home/tt/.cache/joj3/invalid/joj3.log",
+    "expireUnixTimestamp": 0,
+    "effectiveUnixTimestamp": 0,
+    "actorCsvPath": "/home/tt/.config/joj/students.csv",
+    "maxTotalScore": 100,
+    "stage": {
+        "sandboxExecServer": "172.17.0.1:5051",
+        "sandboxToken": "",
+        "outputPath": "/tmp/joj3_result.json",
+        "stages": [
+            {
+                "name": "Health Check",
+                "group": "",
+                "executor": {
+                    "name": "local",
+                    "with": {
+                        "default": {
+                            "args": [],
+                            "env": [
+                                "PATH=/usr/bin:/bin:/usr/local/bin"
+                            ],
+                            "stdin": {
+                                "content": ""
+                            },
+                            "stdout": {
+                                "name": "stdout",
+                                "max": 33554432,
+                                "pipe": true
+                            },
+                            "stderr": {
+                                "name": "stderr",
+                                "max": 33554432,
+                                "pipe": true
+                            },
+                            "cpuLimit": 10000000000,
+                            "clockLimit": 20000000000,
+                            "memoryLimit": 268435456,
+                            "stackLimit": 0,
+                            "procLimit": 50,
+                            "cpuRateLimit": 0,
+                            "cpuSetLimit": "",
+                            "copyIn": {},
+                            "copyInCached": {},
+                            "copyInDir": ".",
+                            "copyOut": [
+                                "stdout",
+                                "stderr"
+                            ],
+                            "copyOutCached": [],
+                            "copyOutMax": 0,
+                            "copyOutDir": "",
+                            "tty": false,
+                            "strictMemoryLimit": false,
+                            "dataSegmentLimit": false,
+                            "addressSpaceLimit": false
+                        },
+                        "cases": [
+                            {
+                                "args": [
+                                    "/usr/local/bin/repo-health-checker",
+                                    "-root=.",
+                                    "-repoSize=10.0",
+                                    "-checkFileSumList=",
+                                    "-checkFileNameList="
+                                ]
+                            },
+                            {
+                                "args": [
+                                    "/usr/local/bin/joint-teapot",
+                                    "joj3-check-env",
+                                    "/home/tt/.config/teapot/teapot.env",
+                                    "--grading-repo-name",
+                                    "JOJ3-config-generator",
+                                    "--scoreboard-filename",
+                                    "scoreboard.csv"
+                                ],
+                                "env": [
+                                    "REPOS_DIR=/home/tt/.cache",
+                                    "LOG_FILE_PATH=/home/tt/.cache/joint-teapot-debug.log"
+                                ]
+                            }
+                        ]
+                    }
+                },
+                "parsers": [
+                    {
+                        "name": "healthcheck",
+                        "with": {
+                            "score": 0
+                        }
+                    },
+                    {
+                        "name": "debug",
+                        "with": {}
+                    }
+                ]
+            }
+        ],
+        "preStages": [],
+        "postStages": [
+            {
+                "name": "teapot",
+                "group": "",
+                "executor": {
+                    "name": "local",
+                    "with": {
+                        "default": {
+                            "args": [
+                                "/usr/local/bin/joint-teapot",
+                                "joj3-all-env",
+                                "/home/tt/.config/teapot/teapot.env",
+                                "--grading-repo-name",
+                                "JOJ3-config-generator",
+                                "--max-total-score",
+                                "0",
+                                "--issue-label-name",
+                                "Kind/Testing",
+                                "--issue-label-color",
+                                "#795548",
+                                "--scoreboard-filename",
+                                "scoreboard.csv"
+                            ],
+                            "env": [
+                                "REPOS_DIR=/home/tt/.cache",
+                                "LOG_FILE_PATH=/home/tt/.cache/joint-teapot-debug.log"
+                            ],
+                            "stdin": {
+                                "content": ""
+                            },
+                            "stdout": {
+                                "name": "stdout",
+                                "max": 33554432,
+                                "pipe": true
+                            },
+                            "stderr": {
+                                "name": "stderr",
+                                "max": 33554432,
+                                "pipe": true
+                            },
+                            "cpuLimit": 30000000000,
+                            "clockLimit": 60000000000,
+                            "memoryLimit": 268435456,
+                            "stackLimit": 0,
+                            "procLimit": 50,
+                            "cpuRateLimit": 0,
+                            "cpuSetLimit": "",
+                            "copyIn": {},
+                            "copyInCached": {},
+                            "copyInDir": ".",
+                            "copyOut": [
+                                "stdout",
+                                "stderr"
+                            ],
+                            "copyOutCached": [],
+                            "copyOutMax": 0,
+                            "copyOutDir": "",
+                            "tty": false,
+                            "strictMemoryLimit": false,
+                            "dataSegmentLimit": false,
+                            "addressSpaceLimit": false
+                        },
+                        "cases": []
+                    }
+                },
+                "parsers": [
+                    {
+                        "name": "log",
+                        "with": {
+                            "msg": "joj3 summary"
+                        }
+                    },
+                    {
+                        "name": "debug",
+                        "with": {}
+                    }
+                ]
+            }
+        ]
+    }
+}

tests/convert/empty/task.toml

@@ -0,0 +1,2 @@
+name = "invalid commit"
+max-total-score = 0

tests/convert/full/task.toml

@@ -1,12 +1,12 @@
 name = "hw7 ex3" # task name, will be shown in the issue title
 
-# scoreboard file name in grading repo, "auto" for automatic generation, optional
+# scoreboard file name in grading repo, "auto" for automatic generation, default: scoreboard.csv
 scoreboard = "auto"
-# scoreboard = "scoreboard.md" # use this if you want to specify a custom scoreboard
+# scoreboard = "scoreboard-42.csv" # use this if you want to specify a custom scoreboard
 
 # task triggered not in this time period will not pass the health check
-time.begin = 2024-12-29 23:59:59 # begin time, optional
-time.end = 2024-12-30 23:59:59 # end time, optional
+time.begin = 2024-12-29 23:59:59 # begin time, default: no start time, do not check
+time.end = 2024-12-30 23:59:59 # end time, default: no end time, do not check
 
 # explanation of the following config:
 # if the submission is within 0-24 hours late from time.end,
@@ -26,10 +26,20 @@ groups.time-period-hour = [24, 1]
 [[stages]]
 # stage name, content in the `[]` set the group
 # conventional commit message needs to contain the group name to run it
+# group can be omitted so that every commit will run this stage
 # e.g. commit msg "test(hw7): run yes" will not run this stage
 # commit msg "test(hw7): run yes [no]" will run this stage
 name = "Generate yes.txt [no]"
 
+# ===================================================
+# ========== executor related config start ==========
+# ===================================================
+
+# executor runs the command in a limited sandbox, each stage uses a unique new sandbox
+# by default the sandbox does not share files and env vars with the host
+# so we need to set env vars and import files to it, and export files for later stages
+# limits can be applied on time, memory, file size, process count
+
 # environment variables, will be set in the sandbox
 # by default, "PATH=/usr/bin:/bin:/usr/local/bin" will be inserted in the front
 env = ["THE_ANSWER=42"]
@@ -58,6 +68,16 @@ limit.stdout = "32m" # stdout size limit, default: "32m"
 limit.stderr = "32m" # stderr size limit, default: "32m"
 limit.proc = 50 # process limit, default: 50
 
+# =================================================
+# ========== executor related config end ==========
+# =================================================
+
+# =================================================
+# ========== parser related config start ==========
+# =================================================
+
+# parser parses the output of the executor and generates comments
+
 # parsers to use for this stage
 # parsers will be run in the order they are listed,
 # which defines the order of the output comment
@@ -174,3 +194,10 @@ case2.limit.mem = "512m" # override memory limit for case2
 # also, you can put .in and .out files in other directories
 # case3.in = "other/cases/case3.in"
 # case3.out = "other/cases/case3.out"
+
+# ===============================================
+# ========== parser related config end ==========
+# ===============================================
+
+# all supported fields are listed here in 1 stage, but usually you need multiple stages
+# for a real world example, please refer to playground repo

tests/convert/test_convert_cases.py

@@ -25,6 +25,10 @@ def test_elf() -> None:
     load_case("elf")
 
 
+def test_empty() -> None:
+    load_case("empty")
+
+
 def test_full() -> None:
     load_case("full")