Skip to content

Commit

Permalink
Avoid platform-specific code in markdown:check-links task
Browse files Browse the repository at this point in the history
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.
  • Loading branch information
per1234 committed Oct 16, 2024
1 parent 51b3eac commit a7443f8
Showing 1 changed file with 28 additions and 35 deletions.
63 changes: 28 additions & 35 deletions Taskfile.yml
Original file line number Diff line number Diff line change
Expand Up @@ -318,46 +318,39 @@ tasks:
# Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-markdown-task/Taskfile.yml
markdown:check-links:
desc: Check for broken links
vars:
# The command is defined in a Taskfile variable to allow it to be broken into multiple lines for readability.
# This can't be done in the `cmd` object of the Taskfile because `npx --call` uses the native shell, which causes
# standard newline escaping syntax to not work when the task is run on Windows.
#
# Using -regex instead of -name to avoid Task's behavior of globbing even when quoted on Windows
# The odd method for escaping . in the regex is required for windows compatibility because mvdan.cc/sh gives
# \ characters special treatment on Windows in an attempt to support them as path separators.
#
# prettier-ignore
CHECK_LINKS_COMMAND:
"
find . \
-type d -name \".git\" -prune -o \
-type d -name \".licenses\" -prune -o \
-type d -name \"__pycache__\" -prune -o \
-type d -name \"node_modules\" -prune -o \
-regex \".*[.]md\" \
-exec \
markdown-link-check \
--quiet \
--config \"./.markdown-link-check.json\" \
\\{\\} \
+
"
deps:
- task: docs:generate
- task: npm:install-deps
cmds:
- |
if [[ "{{.OS}}" == "Windows_NT" ]]; then
# npx --call uses the native shell, which makes it too difficult to use npx for this application on Windows,
# so the Windows user is required to have markdown-link-check installed and in PATH.
if ! which markdown-link-check &>/dev/null; then
echo "markdown-link-check not found or not in PATH. Please install: https://github.com/tcort/markdown-link-check#readme"
exit 1
fi
# Default behavior of the task on Windows is to exit the task when the first broken link causes a non-zero
# exit status, but it's better to check all links before exiting.
set +o errexit
STATUS=0
# Using -regex instead of -name to avoid Task's behavior of globbing even when quoted on Windows
# The odd method for escaping . in the regex is required for windows compatibility because mvdan.cc/sh gives
# \ characters special treatment on Windows in an attempt to support them as path separators.
for file in $(find . -regex ".*[.]md"); do
markdown-link-check \
--quiet \
--config "./.markdown-link-check.json" \
"$file"
STATUS=$(( $STATUS + $? ))
done
exit $STATUS
else
npx --package=markdown-link-check --call='
STATUS=0
for file in $(find . -regex ".*[.]md"); do
markdown-link-check \
--quiet \
--config "./.markdown-link-check.json" \
"$file"
STATUS=$(( $STATUS + $? ))
done
exit $STATUS
'
fi
npx \
--package=markdown-link-check \
--call='{{.CHECK_LINKS_COMMAND}}'
# Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-markdown-task/Taskfile.yml
markdown:fix:
Expand Down

0 comments on commit a7443f8

Please sign in to comment.