Just: add some docs in source

Author: redsun82

misc/just/build.just

@@ -1,12 +1,19 @@
+# Helper build recipes
+
 import "defs.just"
 
+# Build the given language-specific CLI distribution
 _build_dist LANGUAGE: _require_semmle_code (_maybe_build_dist LANGUAGE)
 
+# Build the language-specific distribution if we are in an internal repository checkout
+# Otherwise, do nothing
 [no-exit-message]
 _maybe_build_dist LANGUAGE: (_if_in_semmle_code ('cd "$SEMMLE_CODE"; tools/bazel run //language-packs:intree-' + LANGUAGE) '# using codeql from PATH, if any')
 
+# Call bazel. Uses our official bazel wrapper if we are in an internal repository checkout
 [no-cd, no-exit-message]
 _bazel COMMAND *ARGS: (_if_in_semmle_code 'cd "$SEMMLE_CODE"; tools/bazel' 'bazel' COMMAND ARGS)
 
+# Call sembuild (requires an internal repository checkout)
 [no-cd, no-exit-message]
 _sembuild *ARGS: (_run_in_semmle_code "./build" ARGS)

misc/just/forward.just

@@ -1,5 +1,9 @@
+# Common verbs
+# See README.md in this directory for an overview.
+
 import "lib.just"
 
+
 # copy&paste necessary for each command until proper forwarding of multiple args is implemented
 # see https://github.com/casey/just/issues/1988
 

misc/just/lib.just

@@ -1,35 +1,44 @@
+# Helper recipes
+
 import "build.just"
 import "format.just"
 
+# Run language tests. `BASE_FLAGS` are used by default, `ALL_CHECK_FLAGS` are used if
+# `--all-checks` or `+` is passed along in `EXTRA_ARGS`
 [no-cd, positional-arguments, no-exit-message]
 @_codeql_test LANGUAGE BASE_FLAGS ALL_CHECKS_FLAGS EXTRA_ARGS:
     {{ tsx }} "{{ source_dir() }}/codeql-test-run.ts" "$@"
 
+# Run all language tests in ROOTS for a language. This is intended to be called by CI
 [no-cd, positional-arguments, no-exit-message]
 @_language_tests EXTRA_ARGS SOURCE_DIR +ROOTS: _require_semmle_code
     {{ tsx }} "{{ source_dir() }}/language-tests.ts" "$@"
 
-
-
+# Run integration tests. Requires an internal repository checkout
 [no-cd, no-exit-message]
 _integration_test *ARGS: _require_semmle_code (_run "$SEMMLE_CODE/tools/pytest" ARGS)
 
+# Generic run command recipe that can be used by other recipes, with nice rendering
 [no-cd]
 _run +ARGS:
     {{ cmd_sep }}{{ ARGS }}{{ cmd_sep }}
 
+# Run a command in a specific directory
 [no-cd]
 _run_in DIR +ARGS:
     {{ cmd_sep }}cd "{{ DIR }}"; {{ ARGS }}{{ cmd_sep }}
 
+# Run a command in the internal repository checkout
 [no-cd]
 _run_in_semmle_code +ARGS: _require_semmle_code (_run_in "$SEMMLE_CODE" ARGS)
 
+# Run a just recipe
 [no-cd, positional-arguments, no-exit-message]
 @_just +ARGS:
     echo "-> just $@"
     "{{ JUST_EXECUTABLE }}" "$@"
 
+# Run a just recipe, but only if we are not on CI
 [no-cd, positional-arguments]
 @_if_not_on_ci_just +ARGS:
     if [ "${GITHUB_ACTIONS:-}" != "true" ]; then \