Merge pull request #10603 from cabalism/add/typo-checking-10601

mergify[bot] · web-flow · commit da40ea625668 · 2024-12-02T02:59:11.000Z
Add typo checking for *.rst and *.md files
diff --git a/.github/workflows/typos.yml b/.github/workflows/typos.yml
@@ -0,0 +1,32 @@
+name: Typos
+
+on:
+  pull_request:
+  push:
+    branches: ["master"]
+
+env:
+  TYPOS_VER: v1.28.1
+  TYPOS_PLATFORM: x86_64-unknown-linux-musl
+
+jobs:
+  typos:
+    defaults:
+      run:
+        shell: bash
+    runs-on: ubuntu-latest
+
+    steps:
+
+    - uses: actions/checkout@v4
+
+    - run: |
+        wget -q https://github.com/crate-ci/typos/releases/download/${{ env.TYPOS_VER }}/typos-${{ env.TYPOS_VER }}-${{ env.TYPOS_PLATFORM }}.tar.gz
+        tar -xf typos-${{ env.TYPOS_VER }}-${{ env.TYPOS_PLATFORM }}.tar.gz --one-top-level=typos-${{ env.TYPOS_VER }}
+        mkdir -p "$HOME/.local/bin"
+        mv typos-${{ env.TYPOS_VER }} "$HOME/.local/bin/typos-${{ env.TYPOS_VER }}"
+        chmod +x "$HOME/.local/bin/typos-${{ env.TYPOS_VER }}/typos"
+        echo "$HOME/.local/bin/typos-${{ env.TYPOS_VER }}" >> $GITHUB_PATH
+
+    - run: make users-guide-typos
+    - run: make markdown-typos
diff --git a/.typos.toml b/.typos.toml
@@ -0,0 +1,2 @@
+[default]
+extend-ignore-re = ["(?s)(#|//)\\s*spellchecker:off.*?\\n\\s*(#|//)\\s*spellchecker:on"]
diff --git a/Cabal/ChangeLog.md b/Cabal/ChangeLog.md
@@ -773,7 +773,7 @@
   * Many checks added for common mistakes
   * New `--package-db=` option for specific package databases
   * Many internal changes to support cabal-install
-  * Stricter parsing for version strings, eg dissalows "1.05"
+  * Stricter parsing for version strings, eg disallows "1.05"
   * Improved user guide introduction
   * Programatica support removed
   * New options `--program-prefix/suffix` allows eg versioned programs
diff --git a/Makefile b/Makefile
@@ -60,7 +60,7 @@ lint-json: ## Run HLint in JSON mode
 # local checks
 
 .PHONY: checks
-checks: whitespace style lint-json
+checks: whitespace users-guide-typos markdown-typos style lint-json
 
 # source generation: SPDX
 
@@ -268,3 +268,26 @@ PROCS := $(shell sysctl -n hw.logicalcpu)
 else
 PROCS := $(shell nproc)
 endif
+
+.PHONY: typos-install
+typos-install: ## Install typos-cli for typos target using cargo
+	cargo install typos-cli
+
+GREP_EXCLUDE := grep -v -E 'dist-|cabal-testsuite|python-'
+FIND_NAMED := find . -type f -name
+
+.PHONY: users-guide-typos
+users-guide-typos: ## Find typos in users guide
+	cd doc && $(FIND_NAMED) '*.rst' | xargs typos
+
+.PHONY: users-guide-fix-typos
+users-guide-fix-typos: ## Fix typos in users guide
+	cd doc && $(FIND_NAMED) '*.rst' | xargs typos --write-changes
+
+.PHONY: markdown-typos
+markdown-typos: ## Find typos in markdown files
+	$(FIND_NAMED) '*.md' | $(GREP_EXCLUDE) | xargs typos
+
+.PHONY: markdown-fix-typos
+markdown-fix-typos: ## Fix typos in markdown files
+	$(FIND_NAMED) '*.md' | $(GREP_EXCLUDE) | xargs typos --write-changes
diff --git a/README.md b/README.md
@@ -64,7 +64,7 @@ Currently, we only provide binaries for `x86_64` platforms.
 
 
 2. Even more cutting-edge binaries built from pull requests are always available
-   from the `Validate` worklow page on GitHub, at the very bottom of the page,
+   from the `Validate` workflow page on GitHub, at the very bottom of the page,
    or from the `build-alpine` workflow for statically linked Linux builds.
 
 Ways to build `cabal-install` for everyday use
diff --git a/doc/README.md b/doc/README.md
@@ -40,6 +40,29 @@ either from the root of the cabal repository or from the `docs/` subdirectory. Y
 
 In some cases, you may have to add a bound manually to `requirements.in`, e.g. `requests >= 2.31.0`.
 
+### How to check spelling
+
+To check for typos, run `make typos` and to fix them, run `make fix-typos`. Fixing might fail.
+
+> If there is any ambiguity (multiple possible corrections),
+> `typos` will just report it to the user and move on.
+>
+> SOURCE: [typos/Getting Started](https://github.com/crate-ci/typos#getting-started)
+
+```
+# spellchecker:off
+$ make users-guide-typos
+cd doc && find . -type f -name '*.rst' | xargs typos
+error: `managable` should be `manageable`, `manageably`
+  --> doc/getting-started.rst:75:6
+   |
+75 | more managable building blocks.
+   |      ^^^^^^^^^
+   |
+make: *** [Makefile: users-guide-typos] Error 2
+# spellchecker:on
+```
+
 ### Gitpod workflow
 
 From a fork of cabal, these docs can be edited online with
diff --git a/doc/cabal-commands.rst b/doc/cabal-commands.rst
@@ -395,7 +395,7 @@ cabal list
 cabal info
 ^^^^^^^^^^
 
-``cabal info [FLAGS] PACKAGES`` displays useful informations about remote
+``cabal info [FLAGS] PACKAGES`` displays useful information about remote
 packages.
 
 .. option:: --package-db=DB
@@ -468,7 +468,7 @@ the source code of ``PACKAGES`` locally. By default the content of the
 packages is unpacked in the current working directory, in named subfolders
 (e.g.  ``./filepath-1.2.0.8/``), use ``--destdir=PATH`` to specify another
 folder. By default the latest version of the package is downloaded, you can
-ask for a spefic one by adding version numbers
+ask for a specific one by adding version numbers
 (``cabal get random-1.0.0.1``).
 
 The ``cabal get`` command supports the following options:
@@ -1384,7 +1384,7 @@ A list of all warnings with their constructor:
 - ``no-autogen-paths``: missing autogen ``Paths_*`` modules in ``autogen-modules`` (``cabal-version`` ≥ 2.0).
 - ``no-autogen-pinfo``: missing autogen ``PackageInfo_*`` modules in ``autogen-modules`` *and* ``exposed-modules``/``other-modules`` (``cabal-version`` ≥ 2.0).
 - ``no-glob-match``: glob pattern not matching any file.
-- ``glob-no-extension``: glob pattern not matching any file becuase of lack of extension matching (`cabal-version` < 2.4).
+- ``glob-no-extension``: glob pattern not matching any file because of lack of extension matching (`cabal-version` < 2.4).
 - ``glob-missing-dir``: glob pattern trying to match a missing directory.
 - ``unknown-os``: unknown operating system name in condition.
 - ``unknown-arch``: unknown architecture in condition.
diff --git a/doc/cabal-package-description-file.rst b/doc/cabal-package-description-file.rst
@@ -1114,14 +1114,14 @@ the :pkg-field:`test-module` field.
     An optional list of preprocessors which can generate new modules
     for use in the test-suite.
 
- A list of executabes (possibly brought into scope by
+ A list of executables (possibly brought into scope by
  :pkg-field:`build-tool-depends`) that are run after all other
  preprocessors. These executables are invoked as so: ``exe-name
  TARGETDIR [SOURCEDIRS] -- [GHCOPTIONS]``. The arguments are, in order a target dir for
  output, a sequence of all source directories with source files of
  local lib components that the given test stanza depends on, and
  following a double dash, all options cabal would pass to ghc for a
- build. They are expected to output a newline-seperated list of
+ build. They are expected to output a newline-separated list of
  generated modules which have been written to the targetdir
  (excepting, if written, the main module). This can
  be used for driving doctests and other discover-style tests generated
@@ -3090,8 +3090,8 @@ The auto generated :file:`PackageInfo_{pkgname}` module exports the constant
 which is defined as the version of your package as specified in the
 ``version`` field.
 
-Accessing package-related informations
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Accessing package-related information
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The auto generated :file:`PackageInfo_{pkgname}` module exports the following
 package-related constants:
diff --git a/doc/file-format-changelog.rst b/doc/file-format-changelog.rst
@@ -39,7 +39,7 @@ relative to the respective preceding *published* version.
 ----------------------
 
 * Added field ``code-generators`` to :pkg-section:`test-suite` stanzas. This
-  enumerates executabes (possibly brought into scope by  :pkg-field:`build-tool-depends`) that are run after all other
+  enumerates executables (possibly brought into scope by  :pkg-field:`build-tool-depends`) that are run after all other
   preprocessors. These executables are invoked with a target dir for
   output, a sequence of all source directories with source files of
   local lib components that the given test stanza depends on, and
diff --git a/doc/getting-started.rst b/doc/getting-started.rst
@@ -72,7 +72,7 @@ The ``myapp.cabal`` file is a package description file, commonly referred to as
 
 It contains metadata (package name and version, author name, license, etc.) and sections
 to define package components. Components can be used to split large codebases into smaller,
-more managable building blocks.
+more manageable building blocks.
 A component can be of one of several types (executable, library, etc.) and describes,
 among other things, the location of source files and its dependencies.
 The ``myapp.cabal`` file above defines a single component named ``myapp`` of the executable type.
diff --git a/doc/how-to-use-backpack.rst b/doc/how-to-use-backpack.rst
@@ -16,7 +16,7 @@ are somewhat experimental; while fully supported by cabal-install, they are curr
 
 A Backpack package is defined by use of the
 :pkg-field:`library:signatures` field, or by (transitive) dependency on
-a package that defines some requirements.  To define a parametrized
+a package that defines some requirements.  To define a parameterized
 package, define a signature file (file extension ``hsig``) that
 specifies the signature of the module you want to parametrize over, and
 add it to your Cabal file in the :pkg-field:`library:signatures` field.
@@ -31,10 +31,10 @@ add it to your Cabal file in the :pkg-field:`library:signatures` field.
     concat :: [Str] -> Str
 
 .. code-block:: cabal
-    :caption: parametrized.cabal
+    :caption: parameterized.cabal
 
     cabal-version: 2.2
-    name: parametrized
+    name: parameterized
 
     library
       build-depends: base
@@ -45,14 +45,14 @@ You can define any number of regular modules (e.g., ``MyModule``) that
 import signatures and use them as regular modules.
 
 If you are familiar with ML modules, you might now expect there to be
-some way to apply the parametrized package with an implementation of
+some way to apply the parameterized package with an implementation of
 the ``Str`` module to get a concrete instantiation of the package.
 Backpack operates slightly differently with a concept of *mix-in
 linking*, where you provide an implementation of ``Str`` simply by
 bringing another module into scope with the same name as the
 requirement.  For example, if you had a package ``str-impl`` that provided a
-module named ``Str``, instantiating ``parametrized`` is as simple as
-just depending on both ``str-impl`` and ``parametrized``:
+module named ``Str``, instantiating ``parameterized`` is as simple as
+just depending on both ``str-impl`` and ``parameterized``:
 
 .. code-block:: cabal
     :caption: combined.cabal
@@ -61,7 +61,7 @@ just depending on both ``str-impl`` and ``parametrized``:
     name: combined
 
     library
-      build-depends: base, str-impl, parametrized
+      build-depends: base, str-impl, parameterized
 
 Note that due to technical limitations, you cannot directly define
 ``Str`` in the ``combined`` library; it must be placed in its own
@@ -75,7 +75,7 @@ a requirement ``Str`` and an implementation ``Data.Text``, you can
 line up the names in one of two ways:
 
 * Rename the requirement to match the implementation:
-  ``mixins: parametrized requires (Str as Data.Text)``
+  ``mixins: parameterized requires (Str as Data.Text)``
 * Rename the implementation to match the requirement:
   ``mixins: text (Data.Text as Str)``
 
@@ -91,13 +91,13 @@ the requirements and provided modules renamed to be distinct.
     name: double-combined
 
     library
-      build-depends: base, text, bytestring, parametrized
+      build-depends: base, text, bytestring, parameterized
       mixins:
-        parametrized (MyModule as MyModule.Text) requires (Str as Data.Text),
-        parametrized (MyModule as MyModule.BS) requires (Str as Data.ByteString)
+        parameterized (MyModule as MyModule.Text) requires (Str as Data.Text),
+        parameterized (MyModule as MyModule.BS) requires (Str as Data.ByteString)
 
 Intensive use of Backpack sometimes involves creating lots of small
-parametrized libraries; :ref:`Sublibraries <sublibs>` can be used
+parameterized libraries; :ref:`Sublibraries <sublibs>` can be used
 to define all of these libraries in a single package without having to
 create many separate Cabal packages.  You may also find it useful to use
 :pkg-field:`library:reexported-modules` to reexport instantiated
diff --git a/release-notes/Cabal-3.10.1.0.md b/release-notes/Cabal-3.10.1.0.md
@@ -46,7 +46,7 @@ are listed here.
 
 - Add `PackageInfo_` module [#8534](https://github.com/haskell/cabal/pull/8534)
 
-  - Add `PackageInfo_` module to embed portable package-related informations (issue #3909)
+  - Add `PackageInfo_` module to embed portable package-related information (issue #3909)
 
 - *Cabal-syntax* Add language extensions `DeepSubsumption` and `TypeData` [#8493](https://github.com/haskell/cabal/pull/8493)
 
diff --git a/release-notes/Cabal-3.12.0.0.md b/release-notes/Cabal-3.12.0.0.md
@@ -36,8 +36,8 @@ Cabal and Cabal-syntax 3.12.0.0 changelog and release notes
     package *without* having previously built the dependency.  Instead, we
     promise to the configure phase that we will have built it by the time we
     build the package. This allows us to configure all the packages we intend
-    to load into the repl without building any dependenices which we will load
-    in the same session, because the promise is satisifed due to loading the
+    to load into the repl without building any dependencies which we will load
+    in the same session, because the promise is satisfied due to loading the
     package and its dependency into one multi-session which ensures the
     dependency is built before it is needed.
 
@@ -67,7 +67,7 @@ Cabal and Cabal-syntax 3.12.0.0 changelog and release notes
   prone, as `initialBuildSteps` only handles things like the paths module
   and nothing else.
 
-  To mimick `initialBuildSteps` behaviour when there is no custom Setup, you
+  To mimic `initialBuildSteps` behaviour when there is no custom Setup, you
   can call `repl_setupHooks`.
 
   If you are dealing with a custom setup, you have to invoke
@@ -144,7 +144,7 @@ Cabal and Cabal-syntax 3.12.0.0 changelog and release notes
        large file can reduce overall compile times.
     2. Breaking up the module allows dependent modules to refine their imports
        to just the parts they require, allowing them to start buildling quicker
-       when GHC is run in parrallel make mode ('--ghc-options -j').
+       when GHC is run in parallel make mode ('--ghc-options -j').
 
 - Reimplementing `cabal check` [#7423](https://github.com/haskell/cabal/issues/7423) [#8427](https://github.com/haskell/cabal/pull/8427)
 
@@ -166,7 +166,7 @@ Cabal and Cabal-syntax 3.12.0.0 changelog and release notes
 
     The `./Setup repl` command is modified to allow a user to defer starting
     the repl and instead instruct the command to write the necessary build
-    flags to a directiory. The option is called `--repl-multi-file <DIR>`.
+    flags to a directory. The option is called `--repl-multi-file <DIR>`.
 
     This is useful when starting multi-component sessions, as we want to query
     Setup.hs for the arguments which are needed to build each component but
@@ -264,7 +264,7 @@ Cabal and Cabal-syntax 3.12.0.0 changelog and release notes
     That behavior is desirable to parsing multiline field contents, but it is
     a bit surprising for fields in sections, which we expect to be aligned.
 
-    Such insonsistency seems to be always a mistake, and it's easy to fix once
+    Such inconsistency seems to be always a mistake, and it's easy to fix once
     a machine points it out.
 
 - Add `LexBraces` lexer warning [#8577](https://github.com/haskell/cabal/issues/8577)
diff --git a/release-notes/cabal-install-3.10.3.0.md b/release-notes/cabal-install-3.10.3.0.md
@@ -33,7 +33,7 @@ cabal-install and cabal-install-solver 3.10.3.0 changelog and release notes
 
   Previously, cabal-install would crash when `pkg-config --list-all` contained
   invalid Unicode. With this change, invalid unicode in package descriptions is
-  ignored, and unparseable package names are considered nonexistent.
+  ignored, and unparsable package names are considered nonexistent.
 
 - Script cache dir is the base16 hash of the canonical path of the script. [#9459](https://github.com/haskell/cabal/pull/9459)
 
diff --git a/release-notes/cabal-install-3.12.1.0.md b/release-notes/cabal-install-3.12.1.0.md
@@ -140,7 +140,7 @@ cabal-install 3.12.1.0 changelog and release notes.
 
     In particular this means that cabal-install will create a semaphore which it then
     passes to `./Setup build` (and hence `ghc`) which can be used by `ghc` in order to
-    control how much paralellism it uses, coordinating with other simultaneously running
+    control how much parallelism it uses, coordinating with other simultaneously running
     processes.
 
     This feature requires ghc-9.8 in order to use, as this is the first version of GHC

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	`+[default]`
	`2`	`+extend-ignore-re = ["(?s)(#\|//)\\sspellchecker:off.?\\n\\s(#\|//)\\sspellchecker:on"]`