Merge pull request #23 from input-output-hk/feature/simplify-mdlint-c…

…spell

Feature/simplify mdlint cspell

earthly/cspell/Earthfile

@@ -1,7 +1,11 @@
 # cspell UDCs and Containers.
 VERSION 0.7
 
-CSPELL:
+CSPELL_LOCALLY:
+    # DO NOT RUN THIS UDC INSIDE CONTAINER BUILDS.
+    # IT IS NOT FOR CONTAINER BUILDS.
+    # See: https://github.com/earthly/earthly/issues/580
+
     # Spell checking all docs and code is done with cspell
     # See: cspell.org
     COMMAND
@@ -12,27 +16,18 @@ CSPELL:
     # Unlikely to need to change this.
     ARG cfg_file=cspell.json
 
-    RUN --no-cache if [[ ! -f $src/$cfg_file ]]; then \
-        (>&2 echo "$src/$cfg_file does not exist. Can not check spelling."); \
-        exit 1; \
-    fi
-
-    RUN --no-cache echo Spell Checking Recursively from: $src
+    RUN echo Spell Checking Recursively from: $src
 
-    WITH DOCKER --pull ghcr.io/streetsidesoftware/cspell:latest
-        RUN --no-cache \
-            docker run \
-            --rm \
-            -v $src:/workdir \
-            ghcr.io/streetsidesoftware/cspell:latest \
-            lint .
-    END
+    RUN docker run \
+        --rm \
+        -v $src:/workdir \
+        ghcr.io/streetsidesoftware/cspell:latest \
+        lint .
 
 # A Test and example invocation of the above UDC.
 cspell-test:
-    # Test spellcheck lint checks.
-    # Run with `earthly -P +cspell-test
+    # As notes above, this check must only be run locally.
     LOCALLY
-
-    DO +CSPELL --src=$(echo ${PWD}/../../)
+    # Run with `earthly -P +cspell-test
+    DO +CSPELL_LOCALLY --src=$(echo ${PWD}/../../)
 

earthly/cspell/Readme.md

@@ -16,6 +16,15 @@ multiple source languages and documentation files.
 Tool specific spell checkers are limited in the kinds of files they can check,
 and also will use different configurations, dictionaries and project word lists.
 
+## DO NOT RUN AS PART OF A CONTAINER BUILD TARGET
+
+This UDC is **NOT** intended to be used inside container builds.
+Its sole purpose is to enforce uniform and consistent spell checking for all files in a repository.
+It makes no assumptions about which files may or may not end up inside a container or are part of a build.
+This is *INTENTIONAL*.
+
+IF this UDC is used inside a container build, it is **NOT** a bug if it does not do the correct thing.
+
 ## Invocation
 
 In an Earthfile in your repo, add the following:
@@ -33,7 +42,7 @@ In this use case, the UDC is run Locally, so that the src in the repo can be dir
 ## Configuration
 
 Each repo will need a [`cspell.json`](http://cspell.org/configuration/) file in the root of the repo.
-This file configures cspell.
+This file configures `cspell`.
 The file provided in the `Catalyst-CI` repo should be taken as a starting point
 for new projects.
 
@@ -50,19 +59,19 @@ These words are added to the file:
 
 This can be necessary for the following reasons:
 
-* The built in dictionaries do not contain all possible valid words.
+* The built-in dictionaries do not contain all possible valid words.
   * This is especially true when using names of Companies, Products or Technology.
 * There are identifiers used in the code which are used which fail spell checks.
 
-Words must ONLY be added to project words if they are correctly spelt.
+Words must ONLY be added to project words if they are correctly spelled.
 
 Project words that are added MUST be included in any PR where they became necessary.
 PR Review MUST check that the added words are both reasonable and valid.
 
 Before a word is added to the project dictionary, it should be considered if it is a word likely to occur many times.
 
 Some spelling errors may only occur once, or a handful of times.
-Or, they may be an artefact of the code itself.
+Or, they may be an artifact of the code itself.
 In these cases it is MUCH better to disable the spelling error inline rather than add a word to the project dictionary.
 See [In Document Settings](http://cspell.org/configuration/document-settings/#in-document-settings) for details.
 
@@ -73,6 +82,6 @@ For these files/paths, exclude them from the spell check by adding their filenam
 
 ## Editor Integration
 
-cspell is integrated into VSCode and may be integrated into other Editors.
+`cspell` is integrated into VSCode and may be integrated into other Editors.
 
 The editor integration should pick up the `cspell.json` configuration file and behave exactly the same as the Earthly UDC.

earthly/mdlint/Earthfile

@@ -1,6 +1,10 @@
 VERSION 0.7
 
 MDLINT:
+    # DO NOT RUN THIS UDC INSIDE CONTAINER BUILDS.
+    # IT IS NOT FOR CONTAINER BUILDS.
+    # See: https://github.com/earthly/earthly/issues/580
+
     # Linting is done with MarkdownLint CLI2
     # See: https://github.com/DavidAnson/markdownlint-cli2
     # We use a special container which includes all rule extensions to markdownlint
@@ -20,40 +24,26 @@ MDLINT:
     # Unlikely this ever needs to be changed.
     ARG cfg_file=.markdownlint-cli2.jsonc
 
-    # Ensure the `fix` argument only contains valid values.
-    RUN if [[ "${fix}" != "--fix" && "${fix}" != "" ]]; then \
-        echo "Invalid value for fix argument: ${fix}. It should be either --fix or not set." >&2; \
-        exit 1; \
-    fi
-
-    # Ensure the path to be checked has a mdlint config file.
-    RUN --no-cache if [[ ! -f $src/$cfg_file ]]; then \
-        (>&2 echo "$src/$cfg_file does not exist. Can not run mdLint."); \
-        exit 1; \
-    fi
-
     # Status line for what we are about to do.
-    RUN --no-cache echo Linting Markdown Recursively from: $src
+    RUN echo Linting Markdown Recursively from: $src
 
     # Run the linter with the given arguments, and recursively check all markdown files.
     # The directory to be checked `MUST` have a `.markdownlint-sli2.jsonc` file.
     # cspell: words davidanson
-    WITH DOCKER --pull davidanson/markdownlint-cli2-rules:next
-        # Lint checks should not be cached.
-        RUN --no-cache \
-            docker run \
-            --rm \
-            -v $src:/workdir \
-            davidanson/markdownlint-cli2-rules:next \
-            "**/*.md" \
-            --config $cfg_file \
-            $fix
-    END
+    RUN docker run \
+        --rm \
+        -v $src:/workdir \
+        davidanson/markdownlint-cli2-rules:next \
+        "**/*.md" \
+        --config $cfg_file \
+        $fix
 
 # A Test and example invocation of the above UDC.
 mdlint-test:
     # Test Markdown lint checks.
     # Run with `earthly -P +mdlint-test
+
+    # Must be run LOCALLY as dexcribed above.
     LOCALLY
 
     ARG src=$(echo ${PWD}/../../)

earthly/mdlint/Readme.md

@@ -2,6 +2,15 @@
 
 This Earthly Target and UDC enables uniform linting of Markdown files to maintain consistency and quality.
 
+## DO NOT RUN AS PART OF A CONTAINER BUILD TARGET
+
+This UDC is **NOT** intended to be used inside container builds.
+Its sole purpose is to enforce uniform style rules for all markdown files in a repository.
+It makes no assumptions about which files may or may not end up inside a container or are part of a build.
+This is *INTENTIONAL*.
+
+IF this UDC is used inside a container build, it is **NOT** a bug if it does not do the correct thing.
+
 ## How it works
 
 Linting is performed with the [`mdlint-cli2`](https://github.com/DavidAnson/markdownlint-cli2) program.