Add info for contributors

syntax/just.vim

@@ -9,8 +9,12 @@ if exists('b:current_syntax')
 endif
 
 let b:current_syntax = 'just'
+
+" syncing fromstart prevents mismatched highlighting when jumping around in a justfile
+" linebreaks= keeps multi-line constructs highlighted correctly while typing
 syn sync fromstart linebreaks=10
 
+" a-zA-Z0-9_-
 syn iskeyword @,48-57,_,-
 
 syn match justComment "\v#%([^!].*)?$" contains=@Spell,justCommentTodo
@@ -205,6 +209,7 @@ syn cluster justOtherCurlyBraces contains=justCurlyBraces,justBadCurlyBraces
 
 syn match justFunctionCall "\v\w+%(\s|\\\n)*\(@=" transparent contains=justBuiltInFunction
 
+" error() is intentionally not included in this list
 syn keyword justBuiltInFunction
    \ absolute_path arch blake3 blake3_file cache_directory canonicalize capitalize clean config_directory config_local_directory data_directory data_local_directory env env_var env_var_or_default executable_directory extension file_name file_stem home_directory invocation_directory invocation_directory_native join just_executable justfile justfile_directory just_pid kebabcase lowercamelcase lowercase num_cpus os os_family parent_directory path_exists quote replace replace_regex semver_matches sha256 sha256_file shoutykebabcase shoutysnakecase snakecase titlecase trim trim_end trim_end_match trim_end_matches trim_start trim_start_match trim_start_matches uppercamelcase uppercase uuid without_extension
    \ contained
@@ -257,6 +262,18 @@ syn match justModStatement '^mod' contained
 
 syn match justOptionalFile '\V?' contained
 
+" Most linked colorscheme colors are chosen based on semantics of the color name.
+" Some are for parity with other syntax files (for example, Number for recipe body highlighting
+" is to align with the make.vim distributed with Vim).
+" Deprecated `just` syntaxes are highlighted as Underlined.
+"
+" Colors are linked 'def'(ault) so that users who prefer other colors
+" can override them, e.g. in ~/.vim/after/syntax/just.vim
+"
+" Note that vim-just's highlight groups are an implementation detail and may be subject to change.
+
+" The list of highlight links is sorted alphabetically.
+
 hi def link justAlias                 Statement
 hi def link justAssignmentOperator    Operator
 hi def link justBacktick              Special

tests/justfile

@@ -1,6 +1,15 @@
 # To enable using preview recipes from cwd inside tests/
 set fallback
 
+# Newline-separated list of test cases that are _not_ intended to be runnable justfiles.
+cases_invalid_justfiles := """
+  comment
+  deprecated_obsolete
+  invalid
+  mod
+  set
+"""
+
 # run syntax highlighting tests
 run FILTER='':
   cargo run {{ if FILTER == '' { '' } else { '-- ' + quote(FILTER) } }}
@@ -33,3 +42,16 @@ build:
 lint:
   cargo clippy --all-targets --all-features -- -Dwarnings
   cargo fmt --all -- --check
+
+# for test case development: verify that test case files are valid justfiles
+check-cases:
+  #!/bin/bash
+  set -e
+  declare -rA cases_invalid_justfiles=({{ \
+    replace_regex(cases_invalid_justfiles, "([^\n]+)", '["cases/${1}.just"]=1, ') \
+  }})
+  for case in cases/*.just;do
+    if [[ -z "${cases_invalid_justfiles["$case"]}" ]];then
+      {{quote(just_executable())}} --unstable -f "$case" --list >/dev/null
+    fi
+  done