nimble: support patching multiple files and packages (#625)

We currently patch `cligen/parseopt3` at install time to improve the
command-line parsing in an edge case.

But we may want to patch further packages in the future, e.g. the cmark
package for parsing markdown. Patching that package requires a different
approach, as we need to patch a file outside the directory given by
`nimble path cmark`. We must instead patch a file in the libcmark
submodule before (re-)running `nimble install`, partly because Nimble
doesn't copy a submodule into the installed package directory.

Therefore, let's add a new proc to handle patching of Nimble packages,
making sure that it supports patching:

- a path that is not in the directory of any installed package.

- multiple files (by running `git apply` in the root directory of the
  to-be-patched files).

Other changes:

- Move patching-related files to a new directory.

- Add a `nimble path` helper, which can get paths to multiple packages
  and return an object (rather than a newline-delimited string).

- Support a hash being greater than `int32.high`.

- Remove a `fileExists` check. We already get an error message if the
  `readFile` fails, and it'd be better to use `try` / `except`.

- Prefer to raise a `CatchableError`, rather than an `AssertionDefect`.

- Remove some superfluous patching messages.

Author: ee7

configlet.nimble

@@ -1,4 +1,4 @@
-import std/[hashes, os, strutils]
+import patches/patch
 
 proc getVersionStart: string =
   # Returns the `major.minor.patch` version in the `configlet.version` file
@@ -35,34 +35,5 @@ requires "isaac#45a5cbbd54ff59ba3ed94242620c818b9aad1b5b"     # 0.1.3  (2017-11-
 task test, "Runs the test suite":
   exec "nim r ./tests/all_tests.nim"
 
-# Patch `cligen/parseopt3` so that "--foo --bar" is parsed as two long options,
-# even when `longNoVal` is both non-empty and lacks `foo`.
 before build:
-  # We want to support running `nimble build` before `cligen` is installed, so
-  # we can't `import cligen/parseopt3` and check the parsing directly.
-  # Instead, let's just hash the file and run `git apply` conditionally.
-  # First, get the path to `parseopt3.nim` in the `cligen` package.
-  let (output, exitCode) = gorgeEx("nimble path cligen")
-  if exitCode == 0:
-    let parseopt3Path = joinPath(output.strip(), "cligen", "parseopt3.nim")
-    if fileExists(parseopt3Path):
-      # Hash the file using `std/hashes`.
-      # Note that we can't import `std/md5` or `std/sha1` in a .nimble file.
-      let actualHash = parseopt3Path.readFile().hash()
-      const patchedHash = 1647921161 # Update when bumping `cligen` changes `parseopt3`.
-      if actualHash != patchedHash:
-        echo "Trying to patch parseopt3..."
-        echo "Found " & parseopt3Path
-        let patchPath = thisDir() / "parseopt3_allow_long_option_optional_value.patch"
-        let parseopt3Dir = parseopt3Path.parentDir()
-        # Apply the patch.
-        let cmd = "git -C " & parseopt3Dir & " apply --verbose " & patchPath
-        let (outp, exitCode) = gorgeEx(cmd)
-        echo outp
-        if exitCode != 0:
-          raise newException(AssertionDefect, "failed to apply patch")
-    else:
-      raise newException(AssertionDefect, "file does not exist: " & parseopt3Path)
-  else:
-    echo output
-    raise newException(AssertionDefect, "failed to get cligen path")
+  ensureThatNimblePackagesArePatched()

parseopt3_allow_long_option_optional_value.patch renamed to patches/parseopt3_allow_long_option_optional_value.patch

@@ -1,7 +1,7 @@
-diff --git a/parseopt3.nim b/parseopt3.nim
+diff --git a/cligen/parseopt3.nim b/cligen/parseopt3.nim
 index a865952..850d016 100644
---- a/parseopt3.nim
-+++ b/parseopt3.nim
+--- a/cligen/parseopt3.nim
++++ b/cligen/parseopt3.nim
 @@ -267,8 +267,17 @@ proc doLong(p: var OptParser) =
      p.kind = cmdError
      return

patches/patch.nim

@@ -0,0 +1,61 @@
+import std/[hashes, os, parseutils, strutils]
+
+proc gorgeCheck(cmd, errorMsg: string): string =
+  ## Executes `cmd` at compile time and returns its text output (stdout + stderr).
+  ##
+  ## Raises an exception if the exit code is non-zero, using the given `errorMsg`.
+  var exitCode = -1
+  (result, exitCode) = gorgeEx(cmd)
+  result.stripLineEnd()
+  if exitCode != 0:
+    echo result
+    raise newException(OSError, errorMsg)
+
+type
+  PackagePaths = object
+    cligen: string
+
+proc init(T: typedesc[PackagePaths]): T =
+  ## Returns the absolute paths to Nimble packages that we patch.
+  # Optimization: call `nimble path` only once.
+  result = T()
+  let output = block:
+    var cmd = "nimble path"
+    for fieldName, _ in result.fieldPairs:
+      cmd.add " " & fieldName
+    gorgeCheck(cmd, "failed to get path to packages")
+  var i = 0
+  for fieldVal in result.fields:
+    i += output.parseUntil(fieldVal, {'\n'}, i) + 1
+
+proc patch(dir, patchPath: string;
+           files: varargs[tuple[relPath: string, patchedHash: int64]]) =
+  ## Checks that each file in `files` has the corresponding `patchedHash`, and
+  ## if not, applies the patch at `patchPath` to `dir`.
+  ##
+  ## Raises an exception if the patch could not be applied.
+  # We want to support running `nimble build` before the package is installed,
+  # so we can't `import foo` to check the package's behavior directly.
+  # Instead, hash the files and then run `git apply` when necessary.
+  # Use `std/hashes` to hash - note that we can't import `std/md5` or `std/sha1`
+  # in a .nimble file.
+  for (relPath, patchedHash) in files:
+    if readFile(dir / relPath).hash().int64 != patchedHash:
+      # Apply the patch.
+      let cmd = "git -C " & dir & " apply --verbose " & patchPath
+      discard gorgeCheck(cmd, "failed to apply patch")
+      break
+
+proc patchCligen(packagePaths: PackagePaths) =
+  # Patch `cligen/parseopt3` so that "--foo --bar" is parsed as two long options,
+  # even when `longNoVal` is both non-empty and lacks `foo`.
+  const thisDir = currentSourcePath().parentDir()
+  patch(
+    packagePaths.cligen,
+    thisDir / "parseopt3_allow_long_option_optional_value.patch",
+    ("cligen" / "parseopt3.nim", 1647921161'i64)
+  )
+
+proc ensureThatNimblePackagesArePatched* =
+  let packagePaths = PackagePaths.init()
+  patchCligen packagePaths