fix(swift-doc-coverage, ktlint): skip unresolvable binaryTarget; default ktlint to --format

swift-doc-coverage: SwiftPM resolves all dependencies before any

subcommand runs. Polyglot repos using alef's swift scaffold ship a root

Package.swift whose binaryTarget URL contains placeholder tokens

substituted at release time; locally that URL 404s and the hook fails

before generate-documentation ever runs. Detect the exact SwiftPM

phrasing (failed downloading ... badResponseStatusCode|invalidChecksum|

noChecksum) and skip with a notice.

ktlint: split args into flags/files, inject --format if not present, and

update the modified-files exit message to say 'auto-fixed; re-stage'

instead of the misleading 'use --format to auto-fix'. Aligns ktlint

with the shared-hook policy that any tool capable of auto-fixing should

do so by default.

Author: Goldziher

CHANGELOG.md

@@ -7,6 +7,34 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.1.20] - 2026-05-26
+
+### Fixed
+
+- `swift-doc-coverage`: gracefully skip when SwiftPM cannot resolve a
+  `.binaryTarget` artifact bundle (e.g. polyglot repos using alef's swift
+  scaffold ship a root `Package.swift` whose binaryTarget URL contains
+  placeholder tokens like `v__ALEF_SWIFT_VERSION__/...artifactbundle.zip`
+  that the publish workflow substitutes at release time — locally that URL
+  404s). SwiftPM resolves all dependencies (including binaryTargets) before
+  any subcommand runs, so an unresolvable artifact bundle aborts the run
+  with `failed downloading ... badResponseStatusCode(404)` before
+  `generate-documentation` ever executes. The hook now detects that exit
+  pattern (also `invalidChecksum` and `noChecksum`) and skips with a notice
+  instead of failing the commit, matching the existing graceful-skip paths
+  for "swift not on PATH" and "swift-docc-plugin not declared".
+  (`hooks/swift-doc-coverage/run.sh`)
+
+- `ktlint`: apply `--format` (auto-fix) by default and update the
+  modified-files exit message accordingly. Previously the hook ran ktlint in
+  lint-only mode and produced a misleading "use --format to auto-fix"
+  message even when the consumer's `args:` block already passed `--format`.
+  The hook now splits incoming args into flag/file groups, injects
+  `--format` if absent, and emits `auto-fixed lint issues; re-stage the
+  changed files and re-run.` on the exit-1 modified-files path. Aligns with
+  the shared-hook policy that any tool capable of auto-fixing should do so
+  by default. (`hooks/ktlint/run.sh`)
+
 ## [1.1.19] - 2026-05-26
 
 ### Added

hooks/ktlint/run.sh

@@ -30,15 +30,40 @@ if [[ $# -eq 0 ]]; then
   exit 0
 fi
 
+# Split args into flags (leading dashes) and files (the rest). ktlint expects
+# `<flags> <files>` ordering and treats positional non-dash tokens as paths.
+# pre-commit appends file paths after any `args:` block from the consumer
+# config, so we can rely on flags arriving before files.
+declare -a flags=()
+declare -a files=()
+have_format=0
+for arg in "$@"; do
+  if [[ "${arg}" == --format || "${arg}" == -F ]]; then
+    have_format=1
+    flags+=("${arg}")
+  elif [[ "${arg}" == -* ]]; then
+    flags+=("${arg}")
+  else
+    files+=("${arg}")
+  fi
+done
+
+# Apply autofix by default — `--format` is ktlint's auto-fix flag and
+# matches the shared-hook policy that any tool capable of auto-fixing
+# should do so without consumers having to opt in. Consumers can still
+# explicitly pass `--format` (no-op) or any other ktlint flag via the
+# `args:` block.
+if ((have_format == 0)); then
+  flags+=(--format)
+fi
+
 # Snapshot file hashes pre-lint to detect modifications.
 declare -a before_hashes=()
-for f in "$@"; do
+for f in "${files[@]}"; do
   before_hashes+=("$(_sha256_of "${f}" 2>/dev/null || echo NONE)")
 done
 
-# ktlint can auto-fix via --format flag. When invoked with filenames,
-# it lints them. Combine JAVA_HOME and direct invocation.
-# The executable is a shell script wrapper around a jar, so we need java.
+# ktlint is a self-extracting jar wrapper, so we need java.
 # `jvm_quiet_flags` adds `--sun-misc-unsafe-memory-access=allow` on JDK 23+ via
 # JAVA_OPTS, silencing the noisy "terminally deprecated sun.misc.Unsafe"
 # runtime warnings that ktlint's bundled kotlinc dependencies trigger.
@@ -47,12 +72,12 @@ java_for_probe="${JAVA_HOME:+${JAVA_HOME}/bin/java}"
 java_for_probe="${java_for_probe:-java}"
 mapfile -t quiet_flags < <(jvm_quiet_flags "${java_for_probe}")
 extra_java_opts="${quiet_flags[*]}"
-JAVA_HOME="${JAVA_HOME:-}" JAVA_OPTS="${JAVA_OPTS:-} ${extra_java_opts}" "${exe_path}" "$@"
+JAVA_HOME="${JAVA_HOME:-}" JAVA_OPTS="${JAVA_OPTS:-} ${extra_java_opts}" "${exe_path}" "${flags[@]}" "${files[@]}"
 status=$?
 
 modified=0
 i=0
-for f in "$@"; do
+for f in "${files[@]}"; do
   after="$(_sha256_of "${f}" 2>/dev/null || echo NONE)"
   if [[ "${before_hashes[$i]}" != "${after}" ]]; then
     modified=1
@@ -61,7 +86,7 @@ for f in "$@"; do
 done
 
 if ((modified == 1)); then
-  printf 'ktlint: found lint issues (use --format to auto-fix); re-stage and re-run.\n' >&2
+  printf 'ktlint: auto-fixed lint issues; re-stage the changed files and re-run.\n' >&2
   exit 1
 fi
 

hooks/swift-doc-coverage/run.sh

@@ -89,6 +89,25 @@ for root in "${roots[@]}"; do
     continue
   fi
 
+  # `swift package` resolves all package dependencies — including `.binaryTarget`
+  # entries — before any subcommand runs. Polyglot repos using alef's swift
+  # scaffold ship a root Package.swift with a `.binaryTarget` URL containing
+  # placeholder tokens (e.g. `v__ALEF_SWIFT_VERSION__/...artifactbundle.zip`)
+  # that the publish workflow substitutes at release time. Locally that URL
+  # 404s and SwiftPM exits with `badResponseStatusCode(404)` before
+  # `generate-documentation` even runs. There is nothing the hook can do
+  # about an unresolvable binaryTarget on a developer's machine, so detect
+  # that exact failure mode and skip with a notice. The placeholder token
+  # and the `failed downloading ... badResponseStatusCode` SwiftPM phrasing
+  # are both stable and unique enough to detect reliably.
+  if ((rc != 0)) && grep -E -q "failed downloading .* (badResponseStatusCode|invalidChecksum|noChecksum)" "${log_file}"; then
+    printf 'swift-doc-coverage: skipping %s — binaryTarget artifact is unresolvable (likely a placeholder URL substituted only at publish time).\n' "${root}" >&2
+    printf '  run the hook in CI against a tagged build, or substitute the placeholder locally to enable this hook.\n' >&2
+    rm -f "${log_file}"
+    trap - EXIT
+    continue
+  fi
+
   cat "${log_file}" >&2
 
   if ((rc != 0)); then