Skip to content

Commit fa253b2

Browse files
per1234per1234
committed
Avoid platform-specific code in markdown:check-links task
The `markdown:check-links` task uses the markdown-link-check tool. This tool does not have a capability for discovering Markdown files so it is necessary to use the `find` command to discover the files, then pass their paths to the markdown-link-check tool. Since it is managed as a project dependency using npm, the markdown-link-check tool is invoked using npx. Since the `find` command must be ran in combination with markdown-link-check, it is necessary to use the `--call` flag of npx. Even though Windows contributors are required to use a POSIX-compliant shell such as Git Bash when working with the assets, the commands ran via the `--call` flag are executed using the native shell, which means the Windows command interpreter on a Windows machine even if the task was invoked via a different shell. This causes commands completely valid for use on a Linux or macOS machine to fail to run on a Windows machine due to the significant differences in the Windows command interpreter syntax. During the original development of the task, a reasonably maintainable cross-platform command could not be found. Lacking a better option the hacky approach was taken of using a conditional to run a different command depending on whether the task was running on Windows or not, and not using npx for the Windows command. This resulted in a degraded experience for Windows contributors because they were forced to manually manage the markdown-link-check tool dependency and make it available in the system path. It also resulted in duplication of the fairly complex code contained in the task. Following the elimination of unnecessary complexity in the task code, it became possible to use a single command on all platforms. The Windows command interpreter syntax still posed a difficulty even for the simplified command: A beneficial practice, used throughout the assets, is to break commands into multiple lines to make them and the diffs of their development easier to read. With a POSIX-compliant shell this is accomplished by escaping the introduced newlines with a backslash. However, the Windows command interpreter does not recognize this syntax, making the commands formatted in that manner invalid when the task was ran on a Windows machine. The identified solution was to define the command via a Taskfile variable. The YAML syntax was carefully chosen to support the use of the familiar backslash escaping syntax, while also producing in a string that did not contain this non-portable escaping syntax after passing through the YAML parser.
1 parent 7ef0be0 commit fa253b2

File tree

2 files changed

+58
-82
lines changed

2 files changed

+58
-82
lines changed

‎Taskfile.yml

Lines changed: 30 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -625,54 +625,41 @@ tasks:
625625
# Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-markdown-task/Taskfile.yml
626626
markdown:check-links:
627627
desc: Check for broken links
628-
deps:
629-
- task: docs:generate
630-
- task: npm:install-deps
631-
cmds:
632-
- |
633-
if [[ "{{.OS}}" == "Windows_NT" ]]; then
634-
# npx --call uses the native shell, which makes it too difficult to use npx for this application on Windows,
635-
# so the Windows user is required to have markdown-link-check installed and in PATH.
636-
if ! which markdown-link-check &>/dev/null; then
637-
echo "markdown-link-check not found or not in PATH."
638-
echo "Please install: https://github.com/tcort/markdown-link-check#readme"
639-
exit 1
640-
fi
641-
# Using -regex instead of -name to avoid Task's behavior of globbing even when quoted on Windows
642-
# The odd method for escaping . in the regex is required for windows compatibility because mvdan.cc/sh gives
643-
# \ characters special treatment on Windows in an attempt to support them as path separators.
628+
vars:
629+
# The command is defined in a Taskfile variable to allow it to be broken into multiple lines for readability.
630+
# This can't be done in the `cmd` object of the Taskfile because `npx --call` uses the native shell, which causes
631+
# standard newline escaping syntax to not work when the task is run on Windows.
632+
#
633+
# Using -regex instead of -name to avoid Task's behavior of globbing even when quoted on Windows
634+
# The odd method for escaping . in the regex is required for windows compatibility because mvdan.cc/sh gives
635+
# \ characters special treatment on Windows in an attempt to support them as path separators.
636+
#
637+
# prettier-ignore
638+
CHECK_LINKS_COMMAND:
639+
"
644640
find . \
645-
-type d -name ".git" -prune -o \
646-
-type d -name ".licenses" -prune -o \
647-
-type d -name "__pycache__" -prune -o \
648-
-type d -name "node_modules" -prune -o \
649-
-path "./{{.CLANG_FORMAT_GOLDEN_TEST_DATA_FOLDER}}/samples" -prune -o \
650-
-path "./{{.CLANG_FORMAT_INPUT_TEST_DATA_FOLDER}}/samples" -prune -o \
651-
-regex ".*[.]md" \
641+
-type d -name \".git\" -prune -o \
642+
-type d -name \".licenses\" -prune -o \
643+
-type d -name \"__pycache__\" -prune -o \
644+
-type d -name \"node_modules\" -prune -o \
645+
-path \"./{{.CLANG_FORMAT_GOLDEN_TEST_DATA_FOLDER}}/samples\" -prune -o \
646+
-path \"./{{.CLANG_FORMAT_INPUT_TEST_DATA_FOLDER}}/samples\" -prune -o \
647+
-regex \".*[.]md\" \
652648
-exec \
653649
markdown-link-check \
654650
--quiet \
655-
--config "./.markdown-link-check.json" \
656-
\{\} \
651+
--config \"./.markdown-link-check.json\" \
652+
\\{\\} \
657653
+
658-
else
659-
npx --package=markdown-link-check --call='
660-
find . \
661-
-type d -name ".git" -prune -o \
662-
-type d -name ".licenses" -prune -o \
663-
-type d -name "__pycache__" -prune -o \
664-
-type d -name "node_modules" -prune -o \
665-
-path "./{{.CLANG_FORMAT_GOLDEN_TEST_DATA_FOLDER}}/samples" -prune -o \
666-
-path "./{{.CLANG_FORMAT_INPUT_TEST_DATA_FOLDER}}/samples" -prune -o \
667-
-regex ".*[.]md" \
668-
-exec \
669-
markdown-link-check \
670-
--quiet \
671-
--config "./.markdown-link-check.json" \
672-
\{\} \
673-
+
674-
'
675-
fi
654+
"
655+
deps:
656+
- task: docs:generate
657+
- task: npm:install-deps
658+
cmds:
659+
- |
660+
npx \
661+
--package=markdown-link-check \
662+
--call='{{.CHECK_LINKS_COMMAND}}'
676663
677664
# Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-markdown-task/Taskfile.yml
678665
markdown:fix:

‎workflow-templates/assets/check-markdown-task/Taskfile.yml

Lines changed: 28 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -10,50 +10,39 @@ tasks:
1010
# Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-markdown-task/Taskfile.yml
1111
markdown:check-links:
1212
desc: Check for broken links
13-
deps:
14-
- task: docs:generate
15-
- task: npm:install-deps
16-
cmds:
17-
- |
18-
if [[ "{{.OS}}" == "Windows_NT" ]]; then
19-
# npx --call uses the native shell, which makes it too difficult to use npx for this application on Windows,
20-
# so the Windows user is required to have markdown-link-check installed and in PATH.
21-
if ! which markdown-link-check &>/dev/null; then
22-
echo "markdown-link-check not found or not in PATH."
23-
echo "Please install: https://github.com/tcort/markdown-link-check#readme"
24-
exit 1
25-
fi
26-
# Using -regex instead of -name to avoid Task's behavior of globbing even when quoted on Windows
27-
# The odd method for escaping . in the regex is required for windows compatibility because mvdan.cc/sh gives
28-
# \ characters special treatment on Windows in an attempt to support them as path separators.
13+
vars:
14+
# The command is defined in a Taskfile variable to allow it to be broken into multiple lines for readability.
15+
# This can't be done in the `cmd` object of the Taskfile because `npx --call` uses the native shell, which causes
16+
# standard newline escaping syntax to not work when the task is run on Windows.
17+
#
18+
# Using -regex instead of -name to avoid Task's behavior of globbing even when quoted on Windows
19+
# The odd method for escaping . in the regex is required for windows compatibility because mvdan.cc/sh gives
20+
# \ characters special treatment on Windows in an attempt to support them as path separators.
21+
#
22+
# prettier-ignore
23+
CHECK_LINKS_COMMAND:
24+
"
2925
find . \
30-
-type d -name ".git" -prune -o \
31-
-type d -name ".licenses" -prune -o \
32-
-type d -name "__pycache__" -prune -o \
33-
-type d -name "node_modules" -prune -o \
34-
-regex ".*[.]md" \
26+
-type d -name \".git\" -prune -o \
27+
-type d -name \".licenses\" -prune -o \
28+
-type d -name \"__pycache__\" -prune -o \
29+
-type d -name \"node_modules\" -prune -o \
30+
-regex \".*[.]md\" \
3531
-exec \
3632
markdown-link-check \
3733
--quiet \
38-
--config "./.markdown-link-check.json" \
39-
\{\} \
34+
--config \"./.markdown-link-check.json\" \
35+
\\{\\} \
4036
+
41-
else
42-
npx --package=markdown-link-check --call='
43-
find . \
44-
-type d -name ".git" -prune -o \
45-
-type d -name ".licenses" -prune -o \
46-
-type d -name "__pycache__" -prune -o \
47-
-type d -name "node_modules" -prune -o \
48-
-regex ".*[.]md" \
49-
-exec \
50-
markdown-link-check \
51-
--quiet \
52-
--config "./.markdown-link-check.json" \
53-
\{\} \
54-
+
55-
'
56-
fi
37+
"
38+
deps:
39+
- task: docs:generate
40+
- task: npm:install-deps
41+
cmds:
42+
- |
43+
npx \
44+
--package=markdown-link-check \
45+
--call='{{.CHECK_LINKS_COMMAND}}'
5746
5847
# Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-markdown-task/Taskfile.yml
5948
markdown:fix:

0 commit comments

Comments
 (0)